Xml Doc comment cleanup reassessed #234
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is based off of #220, but rebased against main, and with squashed and reordered commits.
Some changes had to be reverted, like an
IDisposable
implementation that was changed into anIAsyncDisposable
one, which changes behavior, and may not work anymore with "normal"use
applications (this was a product of rebasing, this change was not present in #220. But we do have to be careful here. Anything that is disposable must ALWAYS implementIDisposable
. If the action that does the disposing is asynchronous, it may ALSO implementIAsyncDisposable
, but this is not a requirement.)Also, occurrences like the use of
<code>...</code>
in xml doc comments summaries needed to be removed (unfortunately). They lead to garbled popup descriptions in VSCode, and in Visual Studio there's no discernible difference at all (TODO: raise as bugs to the respective communities).For instance, a section like this:
is rendered like this:
Hence the use of hacks like
<paramref>
:this is, of course, not ideal, but it renders as follows, which is an improvement, but we'll need a more permanent fix:
For the same reason,
true
andfalse
are surrounded by<see cref
tags. Note that in Visual Studio, the coloring is slightly better at times, but still not ideal. Trying to find the lowest common denominator is, frankly speaking, a mess.